/**
 * 生成 stream.doc：用文字描述流的概念、工作过程与应用场景
 */

const fs = require('fs');
const path = require('path');

const target = path.join(__dirname, 'stream.doc');

const content = `流（Stream）概念与应用\n\n` +
`一、什么是流\n` +
`流是一种按顺序连续传输数据的抽象，数据被分割成较小的片段（chunk）\n` +
`逐个在内存中处理，避免一次性把整个数据加载到内存。Node.js 中常见的\n` +
`有四类流：\n` +
`- Readable（可读流）：数据从源头流向使用方，如 fs.createReadStream。\n` +
`- Writable（可写流）：把数据写入目标，如 fs.createWriteStream。\n` +
`- Duplex（双工流）：同时可读可写，如 net.Socket。\n` +
`- Transform（转换流）：在读写过程中对数据做转换，如 zlib、加解密、自定义转换。\n\n` +
`二、工作过程（以可读 -> 转换 -> 可写为例）\n` +
`1) 源头创建 Readable，把数据分块读取；\n` +
`2) Readable.push(chunk) 把数据推给消费者；\n` +
`3) 通过管道 pipeline/pipe 将 Readable 输出交给 Transform；\n` +
`4) Transform 对 chunk 进行处理（如大写、压缩），再交给下游；\n` +
`5) 下游 Writable 接收 chunk 并顺序写入目标；\n` +
`6) 当数据读尽时 push(null) 或触发 end，整条流水线关闭；\n` +
`7) 背压（Backpressure）：当 Writable 来不及处理时会反馈压力，Readable 暂停推送，\n` +
`   待可写后继续，以此保持稳定与低内存占用。\n\n` +
`三、为何使用流\n` +
`- 低内存占用：处理超大文件/长连接而无需一次性读入内存；\n` +
`- 高吞吐：边读边处理，减少等待；\n` +
`- 组合式：通过管道把多个步骤拼接成清晰的处理链。\n\n` +
`四、典型应用场景\n` +
`- 文件：大文件复制、转换（编码、压缩、加密）；\n` +
`- 网络：HTTP 请求/响应体的上传与下载；\n` +
`- 媒体：音视频转码、实时推流；\n` +
`- 数据处理：日志实时处理、ETL、消息队列消费；\n` +
`- 其他：数据库导入导出、逐行处理文本、流式解析。\n\n` +
`五、最佳实践\n` +
`- 使用 pipeline 代替多段 pipe，统一处理错误并在结束时清理；\n` +
`- 始终监听 error 事件；\n` +
`- 关注编码与边界（换行、分隔符）；\n` +
`- 合理拆分 chunk，避免大量字符串拼接导致的性能问题。\n\n` +
`本文件由 Node.js 脚本自动生成。`;

fs.writeFileSync(target, content, 'utf8');
console.log('已生成说明文档:', target);


